<html><!-- Copyright (C) 2007 Laurent A.V. Szyster - Copylef GPL 2.0 -->
<head>
  <title>protocols.js &gt; HTML</title>
  <link href="site.css" type="text/css" rel="stylesheet"></link>
  <link href="protocols.css" type="text/css" rel="stylesheet"></link>
  <script src="firebug.js" type="text/javascript"></script>
</head>

<body>

<div>  
  <h1><a href="index.html">protocols.js</a></h1>
  <div class="menu">
    <a href="documentation.html">Documentation</a> &gt;
    <a href="functions.html">Functions</a>
    <a href="HTTP.html">HTTP</a>
    <a href="CSS.html">CSS</a>
    <a href="JSON.html">JSON</a>
  </div>
  <h2>HyperText Markup Language (HTML)</h2>
  <ol>
    <li><a href="#HTML.onload">Protocols.onload</a></li>
    <li><a href="#HTML.cdata">cdata (string)</a></li>
    <li><a href="#HTML.text">text (element)</a></li>
    <li><a href="#HTML.input">input (element)</a></li>
    <li><a href="#HTML.update">update (element, html)</a></li>
    <li><a href="#HTML.replace">replace (element, html)</a></li>
    <li><a href="#HTML.insert">insert (element, html, adjacency)</a></li>
    <li><a href="#HTML.bind">bind (element, type, fun, bubble, capture)</a></li>
    <li><a href="#HTML.listen">listen (element, type, fun)</a></li>
    <li><a href="#HTML.parse">parse (text)</a></li>
  </ol>
  <h3>Synopsis</h3>
  <p>
    Learning and depending on every <a 
    href="http://www.w3.org/TR/1999/REC-html401-19991224/"
    >HTML</a> document object model APIs is far more costly than mastering 
    once the protocol itself. And practically it is also a lot more 
    efficient and reliable to directly &quot;write&quot; hypertext markup and 
    let each browser parse, instanciate a DOM and render it. 
  </p>
  <p>
    The eight methods of <code>HTML</code> provide just enough support for the 
    most common manipulations of an interactive web page: replace an element, 
    update an element content and insert HTML markup before or after the 
    beginning or the end of an element; attach event listeners; build a query 
    string from HTML form input values; get an element's CDATA text only; 
    escape text as valid CDATA.
  </p>
  <p>
    Many web applications can use these methods only, most entreprise
    applications will. 
  </p>
  <h3><a name="HTML.onload" href="#">Protocols.onload</a></h3>
  <p>
    The <code>onload</code> property of <code>HTML</code> is an array
    of functions that will be called once the HTML page is ready but before
    any linked resources have been loaded.
  </p>
  <pre>HTML.onload.push(function () {
    var hover = ['hover'];
    map(function (el) {
        HTML.listen(el, 'mouseover', function () {
            CSS.add(el, hover);
        });
        HTML.listen(el, 'mouseout', function () {
            CSS.remove(el, /hover\s*/g);
        });
    }, $$('pre.synopsis'));
});</pre>
  <p>
    See <a 
    href="http://dean.edwards.name/weblog/2006/06/again/"
    >http://dean.edwards.name/weblog/2006/06/again/</a>.
  </p>
  <h3><a name="HTML.cdata" href="#">HTML.cdata (string)</a></h3>
  <pre
    class="synopsis" 
    onclick="{HTML.update($('html_cdata'), eval_synopsis(this));}" 
    >HTML.cdata('&lt;tag name=&quot;value&quot; /&gt;')</pre>
  <div id="html_cdata" class="test">...</div>
  <h3><a name="HTML.text" href="#">HTML.text (element)</a></h3>
  <pre
    class="synopsis" 
    onclick="{HTML.update ($('html_text'), eval_synopsis(this));}" 
    >HTML.text($$('ol')[0]);</pre>
  <div id="html_text" class="test">...</div>
  <h3><a name="HTML.input" href="#"
  >HTML.input (elements, query)</a></h3>
  <div class="test">
    <form>Hello <input name="hello" type="text" value="world" /> !</form>
  </div>
  <pre
    class="synopsis" 
    onclick="{HTML.update ($('html_input'), JSON.encode(eval_synopsis(this)));}" 
    >HTML.input($$('form'), {});</pre>
  <div id="html_input" class="test">...</div>
  <h3><a name="HTML.update" href="#"
  >HTML.update (element, html)</a></h3>
  <pre class="synopsis" onclick="{eval_synopsis(this);}" 
    >HTML.update($('html_update'), 'Hello &lt;em&gt;update&lt;/em&gt;!');</pre>
  <div id="html_update" class="test">...</div>
  <h3><a name="HTML.replace" href="#"
  >HTML.replace (element, html)</a></h3>
  <pre class="synopsis" onclick="{eval_synopsis(this);}" 
    >HTML.replace($('html_replace'), 'Hello &lt;em&gt;replace&lt;/em&gt;!');</pre>
  <div id="html_replace" class="test">...</div>
  <h3><a name="HTML.insert" href="#"
  >HTML.insert (element, html, adjacency)</a></h3>
  <pre class="synopsis" onclick="{eval_synopsis(this);}" 
    >HTML.insert($('html_insert'), '&lt;div&gt;up&lt;/div&gt;', 'beforeBegin');</pre>
  <pre class="synopsis" onclick="{eval_synopsis(this);}" 
    >HTML.insert($('html_insert'), '&lt;div&gt;top&lt;/div&gt;', 'afterBegin');</pre>
  <pre class="synopsis" onclick="{eval_synopsis(this);}" 
    >HTML.insert($('html_insert'), '&lt;div&gt;bottom&lt;/div&gt;', 'beforeEnd');</pre>
  <pre class="synopsis" onclick="{eval_synopsis(this);}" 
    >HTML.insert($('html_insert'), '&lt;div&gt;down&lt;/div&gt;', 'afterEnd');</pre>
  <div id="html_insert" class="test">...</div>
  <h3><a name="HTML.bind" href="#"
  >HTML.bind (element, type, listener, bubble, capture)</a></h3>
  <p>
    Bind a function to an element as a listener to event of a given type. 
  </p>
  <pre class="synopsis" onclick="eval_synopsis(this);"
    >HTML.bind($('html_bind_foobar'), 'click', function (event) {
    alert(this.innerHTML);
    return true;
    });</pre>
  <div id="html_bind_foobar" class="test">
    Click here to send an event to the attached listener.
  </div>
  <p>
    Note how <code>this</code> in the bound function refers to the 
    <code>element</code> it was binded to.
  </p>
  <h3><a name="HTML.listen" href="#"
  >HTML.listen (element, type, listener)</a></h3>
  <p>
    Attach a bound or enclosed event listener to an HTML element. It is 
    practical to attach a closure to each elements selected:
  </p>
  <pre class="synopsis" onclick="eval_synopsis(this);"
    >map (function (element) {
    HTML.listen(element, 'click', function () {
        CSS.add (element, ['hidden']);
        });
    }, $$('pre.synopsis'));</pre>
  <p>
    ...
  </p>
  <pre class="synopsis" onclick="eval_synopsis(this);"
    >HTML.listen($('html_listen_bound'), 'click', bindAsEventListener (
    {"hello": "World!"}, function (event) {
        alert(JSON.encode(this));
        return true;
    }
    ));</pre>
  <div id="html_listen_bound" class="test">
    Click here to send an event to the attached listener.
  </div>
  <h3><a name="HTML.parse" href="#"
  >HTML.parse (text)</a></h3>
  <p>
    Parse an (X)HTML text string and return a DOM element node.
  </p>
  <pre class="synopsis" onclick="eval_synopsis(this);"
    >alert(HTML.text(HTML.parse('&lt;span&gt;test&lt;/span&gt;')));</pre>
</div>
<script src="protocols.js" type="text/javascript"></script>
<script src="tests.js" type="text/javascript"></script>
</body>
</html>